Collection of Tools & Utilities

home *** CD-ROM | disk | FTP | other *** search

/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / bbsutil / ghost230.zip / GHOST.DOC < prev next >

Wrap

Text File | 1990-11-01 | 72KB | 1,872 lines

Ghostwriter [2.1] Purpose of this program ...................................... 2 Configuration ................................................ 2 Ghost hello! ................................................. 3 How to use the program ....................................... 4 QuickBBS specific assumptions ................................ 5 Ondate option ................................................ 6 Onday option ................................................. 7 Performing mail check ........................................ 7 How to use the "cosysop" ..................................... 9 Shelling to DOS .............................................. 9 Server requests .............................................. 12 How to use the "trigger" ..................................... 13 Predefined variables ......................................... 14 Message flags ................................................ 15 Inter-zone messages: #define zonegate ........................ 16 National customization: #define country ...................... 17 Addressees list: #define group ............................... 18 User-defined variable: the -d option ......................... 19 Alternate configuration file: the -f option .................. 20 Generate kludge lines: the -k option ......................... 20 Use other sysop name: the -n option .......................... 20 No word wrap: the -s option .................................. 21 No tear line: the -t option .................................. 21 Tear line and origin line .................................... 21 File attaches ................................................ 21 File requests ................................................ 22 Magic filenames .............................................. 23 File compression method ...................................... 23 Override magic filenames ..................................... 24 Optional kludge lines ........................................ 24 Errorlevels returned ......................................... 24 Credits, new releases and "Thank you" ........................ 26 Index ........................................................ 28 _________________________________________ Purpose of this program The ghostwriter can be used to automatically create messages to one or more addressee(s) in different kinds: local, echo, matrix, file attach or file request. Another important function of the program is to scan message areas for messages not received by the sysop and to generate replies and forwarded messages. Last but not least it can be used as a powerful batch processor containing all required variables for Nodelist and other day-dependent file processing. These batch files even may be created from netmail messages addressed to a special "pseudo" user. The program supports the generic message format used world- wide in FidoNet. The QuickBBS message format, originally designed by Adam Hudson, currently used by QuickBBS, FrontDoor/TosScan and RemoteAccess, also fully is supported. Users of BinkleyTerm, FrontDoor or RemoteAccess will need no configuration parameters. You can use this utility in connection with any mailer and editor of your choice assumed your software uses the netmail message header structure as defined in various FSC and FTS documents. Of course the program is zone- and point-smart. The proper ^aINTL, ^aFMPT and ^aTOPT kludges will be included in the netmail message header if neccessary. Mailer specific additional message flags easily can be used. The command "ghost > ghost.cfg" creates a simple config- uration file as required by the program. Edit this file to suit your needs; see the included Sample.Cfg for more details. ___________________________________________________ Configuration There is very little configuration required to get the program up and running. If you use BinkleyTerm 2.30, FrontDoor or Remote- Access the only operating parameters required are "to [name] [ad- dress] {flags}" and "path" lines in Ghost.Cfg. The program tries to locate Binkley.Cfg, Fd.Sys or Config.Ra first in the current subdirectory. If this attempt failed the DOS environment is searched for "set BINKLEY=d:\subdir", "set FD= d:\subdir" or "set RA=d:\subdir". If neither Binkley.Cfg nor Fd.Sys or Config.Ra could be found put Ghost.Exe and Ghost.Cfg in the same subdirectory as BinkleyTerm, FrontDoor or RemoteAccess. You use another mailer? In this case the parameters "sysop", "address" and "netmail" are required in Ghost.Cfg. The "system" parameter is optional: if an ASCII file named "Origin" is located in the subdirectory where the new message(s) will be created it is used for the origin lines. The other optional keywords "nodelist" and "okfile" will enhance the program's possibilities on your system. Ghostwriter [2.1] page 2 To avoid data redundancy the matrix address in any "to [name] [address] {flags}" line may be omitted if a file named Fidouser.Lst is existing in the same subdirectory as stated in the line "nodelist". The format of the Fidouser.Lst is very simple: last name, first name [1..n blanks] [zone:]net/node. Various nodelist compilers (for example Bob Hartman's ParseLst) optionally create this file while translating the nodelist into the binary format used by the mailer software. Since there is no message flag field in the Fidouser.Lst-like file these messages always will have the "private" flag set. However: you should be aware of the fact that the program's execution time due to the required disk access considerable gains, especially if you process large #group lists. In the current version the search time required to locate the very last line in Fidouser.Lst is about five seconds (6 Mhz IBM XT 286 w/287, 512 kb EMS disk cache). ____________________________________________________ Ghost hello! To verify the program has detected correct configuration use the special command line parameter "hello!". If all required parameters ("sysop", "address", "netmail" and optionally "sys- tem", "nodelist" and "okfile") could be found in Ghost.Cfg, Binkley.Cfg, Fd.Sys or Config.Ra this data will be displayed in a window on the screen. If Binkley.Cfg, Fd.Sys or Config.Ra could be located the file Ghost.Cfg is not required for the "hello!" option. Also a "Hello and thank you!"-message to myself will be generated in your netmail directory. If you think this is annoying simply delete this message; otherwise allow your system to export this message during the next netmail export event. Your name and network address will be added to the user list of the program. You will be notified of new program releases as soon as they are available. Ghostwriter [2.1] page 3 __________________________________________ How to use the program To generate messages start ghostwriter with a keyword declared in Ghost.Cfg as command line parameter. This keyword will become the "Subject:" of the message(s) created by the program. If your key- word in the configuration file includes blanks use "_" (under- score) instead on the command line (example: keyword in Ghost.Cfg is "Hi, John"; command line "hi,_john"). The configuration file (default: Ghost.Cfg) must be a plain ASCII file; lines starting with ";" (semicolon) or "%" (percent sign) in the very first column are interpreted as comment lines; everything following and including the comment character from left to right on any line of this file is ignored and also assumed to be a comment. Only blank (hex 20) and/or tab (hex 09) characters are allowed as "white space" to separate keywords, arguments or names. *Note*: instead of writing the full path you may use the macro "netmail" on the "path" line of Ghost.Cfg. "Netmail" will be replaced with the actual name of your netmail directory as found in Binkley.Cfg, Fd.Sys, Config.Ra or Ghost.Cfg. DOS environment strings may be used for any parameter or text in the configuration file. Use the usual %format% to create references to entries to search for in the environment. Please see the Sample.Cfg file for more details on this topic. The only limit of lines in Ghost.Cfg containing "to [name] [address] {flags}" is set by the amount of free memory while the program is up and running. Each addressee consumes 134 bytes of memory. The full zone:net/node.point (four-dimensional) Fidonet address format can be used in the adressees list; it *must* be used to identify your network address in Ghost.Cfg or Bink- ley.Cfg. If "zone:" is missing the receivers net is assumed to be in the same zone as the origin system is located in. If the address field contains no ".point" or ".0" the message is assumed to be destined to the node number found in the address field. Otherwise the message is still sent to the node number, but the kludge ^aTOPT [point #] will be inserted after the message header. Starting with Ghostwriter 1.32 the "address" statement in BinkleyTerm 2.30 or newer is mandatory. Only if the new "four- dimensional" address statement is present in Binkley.Cfg the netmail message headers will contain the proper kludge lines (^aFMPT) and correct zone information. Ghostwriter's origin lines (if used) will confirm the point address format. Ghostwriter [2.1] page 4 The few lines of screen output while the program is working may be re-directed to any file or device. If you like to keep a log about ghostwriter's activities use it for example this way: keyword {-dvariable -ffilename.ext -k -s -t} >> ghost.log The format of the log messages created while executing the program depends on the mailer/BBS software used. If Ghostwriter is used with BinkleyTerm, an Opus-style log format will be written. In case of FrontDoor Joaquim Homrighausen's log format will be used. For RemoteAccess the log format used will be taken from Config.Ra. An other method of logging the program's activities is to use the keyword "#define statuslog [filename | device]". If this line is detected in Ghost.Cfg a second log will be created in the file or device following the "statuslog" keyword. ___________________________________ QuickBBS specific assumptions For operating the program in a QuickBBS message style echomail environment the following assumptions are made: The keyword "#define messagebase QBBS" is present in the top (configuration) section of the Ghost.Cfg file. If this keyword is not present *.MSG style echomail areas are assumed by the program. The keyword "#define QBBSpath [d:\subdir]" is used. The best location is immediately on the next line after the "#define messagebase QBBS". This keyword only is required if neither FrontDoor nor RemoteAccess is used as mailer/BBS software. Normally, this path will be read by the program from Fd.Sys or Config.Ra. A TosScan like Areas.Bbs file is located in the same subdi- rectory as the QuickBBS message base Msg*.Bbs files. This file is required for the mail check option (more on this later) and if Ghostwriter is used to place echomail messages in QuickBBS message boards. References to a specific board number are done in the format path #[nn] where [nn] is a number between 1 and 200. [nn] also must be an active board number on your system; if for a given board number on a "path #[nn]" line no according line in the Areas.Bbs file is found the program notes this in the log file and terminates. Ghostwriter [2.1] page 5 In pure FrontDoor environments no "#define messagebase" statement is required. The program assumes the QuickBBS echomail format if the corresponding path in Fd.Sys is not empty. Also, the Areas.Bbs file is not required: the information of the file Folder.Sys will be used instead. However: even in a QuickBBS style echomail environment the netmail folder still is assumed to contain messages in the standard FidoNet *.Msg format. ___________________________________________________ Ondate option The keyword tag in Ghost.Cfg may be leaded by "ondate yyyy-mm-dd" in column 1, followed by at least one blank character and the keyword/message subject itself. The year must contain four numeric characters, month and date must contain leading zeroes if values below 10 are used. Year, month and day must be separated by a dash (hex 2D) character. If "ondate yyyy-mm-dd" is present the message will only be generated if the current date and "yyyy-mm-dd" match. The string after "ondate yyyy-mm-dd" will become the message subject. The command line parameter for the program must also be "ondate", followed by the other command line options. The only wildcard character allowed in the date string after "ondate" is the question mark ("?"). It acts exactly as the wildcard in DOS' file related commands. A few examples: today is February 3rd, 1990, translated to 1990-02-03 by the program's "ondate" function. ondate 1990-??-03 will match; ondate 1990-02-?? will match; ondate 1990-??-03 will match; ondate 1990-02-04 will not match; ondate 1990-??-01 will not match; ondate 19??-??-?? will match always (never use this!) The command line parameter to execute the program will be "ondate", followed by the other optional parameters. The subject of the message will be the string following the "ondate yyyy-mm- dd" part of the line in Ghost.Cfg. A few examples for this option. Let's assume today's date as February 5th, 1990 and the following line in Ghost.Cfg: ondate 19??-??-05: $fileC:\Misc\Newfiles.Zip Ghostwriter [2.1] page 6 The program is started with "ghost ondate" and maybe some other command line options (-ffilename.ext, -k, -s, -t). The line "ondate 19??-??-05 $fileC:\Misc\NewfilesZip" in Ghost.Cfg tells the program to send C:\Misc\Newfiles.Zip on each 5th of the month to the names found on the next "to" line, no matter if this is a single name or a "#defined" group. ondate 19??-08-03: Best wishes for your birthday! Again, the program is started with "ghost ondate". The message with the subject "Best wishes for your birthday!" will *not* be generated, since today's date is February 5th. Only if "ghost ondate" is executed on the 3rd of August this message will be created. Note: you may only use one "ondate yyyy-mm-dd" tag for the same day. If there are more "ondate yyyy-mm-dd [subject]" lines in Ghost.Cfg matching the same date only the first match will be covered. ____________________________________________________ Onday option This option is very similar to "ondate": instead of comparing a "yyyy-mm-dd" string with the current system date the program searches Ghost.Cfg for a tag line "onday <dayname> <subject>". Valid strings for <dayname> are Monday, Tuesday, Wednesday, Thursday, Friday, Saturday and Sunday. Neither the day names listed in Ghost.Cfg in the "#define country" section nor the "country" settings in your Config.Sys do affect the day names required by the "onday" option. These day names always must be written in English. ___________________________________________ Performing mail check The program can be used to perform a check for messages not received by the sysop within a certain number of days. First, in the "#define section" of the configuration file, use "#define bouncelimit n" to define a number between 1 and 65000. "N" is the number of days the ghostwriter will wait for you to read messages addressed to you. Next, declare a label called "mailcheck" in Ghost.Cfg. Do *not* use a "to" line after the label line; the names and netword addresses will be found by the ghostwriter itself. The next non-comment line is a "path" line. There are two options: #1: Write only one subdirectory name/board number after the "path" keyword. The mail check will be performed only in this subdirectory/QuickBBS echomail board. Ghostwriter [2.1] page 7 #2: Use "path all" to perform a mail check in all message subdirectories/boards available on the system. In a *.Msg echo- mail environment the Areas.Bbs file must be present in the mailer's subdirectory. This file should have the same structure as the Areas.Bbs file used for example by ConfMail or Qmail (drive:\subdir\... [blank] echo tag [blank] list of nodes). In a QuickBBS style echomail environment the board number is the first item on each line of this file. In FrontDoor environments this file is not required. If you use the "path all" option the netmail directory also will be included in the mail check. The same line may include the keywords "answer" and "for- ward". "Answer" tells the program to create replies into the netmail subdirectory. "Forward" instructs the program to forward a copy of the message not received yet by the sysop into the netmail area. This forwarded message will have the "received" and "sent" flag set. If "forward" is missing the non-received message may be lost during the next message kill/renumber event. After the "mailcheck" and "path" lines the text of the message must be located. Now the program may be started with the command line parameter "mailcheck". It will scan the message subdirectories/QuickBBS message boards given on the "path" line. If there are any messages not received by you within "bouncelimit" days first the "received" flag for each of those messages will be set. Next the answer message is generated, depending on the presence of the "answer" keyword. Finally, if "forward" was present, a copy of the unreceived message destined to the sysop will be placed into the netmail directory. By default all messages will be replied; you may override this by defining a special group called "mailcheck". If this group is present only messages from this group members will be replied; other messages will be ignored. This mailcheck group too must be defined in the "#define" section of the configuration file; before any "to", "path" and message text lines. See page 18 for more details on how to define groups. It's not necessary to include the network addresses or message flages for the "mailcheck" group members. The address of the reply will be taken from the original message header (if it was a netmail message) or preferably from the "^aMSGID: <message ID> " or " * Origin: " line (if it was an echomail message). In a QuickBBS message style environment a special built-in tag is available: "report". The program's report function scans all echomail boards for new messages addressed to the sysop. By default the result of this message scan is placed as private netmail message in the netmail folder. Using the command line switch "-d<filename.ext>" or "-d<any device>" the report is sent to <filename.ext> or <any device>. Ghostwriter [2.1] page 8 ________________________________________ How to use the "cosysop" In connection with the mail check option there's a special keyword available: "#define cosysop". The execution of the mail check option will differ from its "normal" behaviour if this statement is present in the confi- guration file. All not yet received messages addressed to the sysop will be forwarded to the members of the group "cosysop" (for more details on defining groups see page #18). The original message will be marked as "received", the forwarded copies will have the corresponding message flags set as found on the lines for the "cosysop" group members names and network addresses. This message forwarding is done independent of the probably used value for "bouncelimit". No matter how old (or how new) the messages are: if they are addressed to the sysop and have not yet been received they will be forwarded to the "cosysop" group. Also messages destined to "Sysop", "all Sysops" or similar constructions or the sysop's first name will be forwarded by the program. The forwarded messages will reside in the netmail directory, no matter if the original message was an echomail or matrix message. Messages forwarded by the program -- no matter if "#define cosysop" is present or not -- will have a short trailer at the start of the message text. This trailer lines will show the sender's name and address, the original message date, the echo- tag for the corresponding area (from the Areas.Bbs-like file) or the name of the message subdirectory (if no echo-tag could be found). An other keyword also alters the program's behaviour while performing mail check: "#define purge". It must only be used if there's a defined group with the same name, "purge". As with the group "mailcheck" the "purge" group members need no network addresses or message flags. The "purge" and the "mailcheck" group are simple lists of names (firstname lastname); each one on a single line without any further text. If "#define purge" is active in Ghost.Cfg messages from one of the "purge" group members will not be replied or forwarded to the sysop or the cosysop group members. Furthermore, if in any message area there are messages from or to one of the "purge" group members this messages will be deleted. If the "#define purge" keyword is not active, this messages will not be deleted. In this case the "purge" group just acts as a list of persons from which the messages should be ignored. Ghostwriter [2.1] page 9 _________________________________________________ Shelling to DOS DOS commands may be executed from within ghostwriter. One or more "dos [command]" lines in Ghost.Cfg are used for this purpose. As shown in the file Sample.Cfg the only place where a "dos [com- mand]" statement may be used (and makes sense) is after the "key- word" line and before any "to [first name] [last name] [address] {flags}" or "to #group [group name]" lines. Depending on DOS version, installed device drivers and any TSR's on a 640 kb computer there are approximately 540 kb available for shelling to other applications. The program tries to swap itself to EMS memory; if this is not possible a swap file in the subdirectory found indicated by the TMP or TEMP environ- ment variable will be created. Here's a memory map from my machine during execution of a program from within "Ghostwriter": Machine Type: PC/XT Model 286 DOS Version: 4.01 ROM Date: 04/21/86 Resident extensions... Address Program Parent Seg Bytes Hooked Vectors ───────── ──────── ──────── ─── ────── ──────────────────────────────── 0B43:0000 Config N/A 5 41632 02 08 09 0A 0E 10 19 1B 29 2F 33 70 76 1572:0000 DOS N/A 2 6512 2E 170B:0000 PC-CACHE DOS 1 6992 13 21 67 18CF:0000 GHOST DOS 2 5648 1A32:0000 DOS N/A 3 6400 22 24 Memory Control Block overhead 15 240 Free memory 2 541824 Next command load address: 1BC6:0000 Before shelling to the command following the "dos" statement a check is done to verify the COMSPEC entry in the computer's environment. If COMSPEC is not found the program will log this to the logging device (i.e. the screen, a file or a printer) and assume normal execution. If the command called from within ghostwriter produces redirectable I/O its output will be to the same logging device as used by ghostwriter. An example: you direct the ghostwriter's log to Binkley.Log using the DOS append symbol ">>". The line "dos mem /program" is executed. Its output will be found in Binkley's log file. If you execute "dos mem > f:\mem.txt" the child process program will direct its output to an other file. Ghostwriter [2.1] page 10 After a "dos [command]" line has been detected and COMSPEC could be located the current content of the screen and the cursor position are saved. Execution of the "shelled" application begins. Afterwards the screen is restored to its old state, the cursor position is updated and the shelled program's exit code (errorlevel) is noted in a log line. The ghostwriter returns to the same drive and subdirectory where it resided before executing the shelled command. If more than one "dos [command]" line for the tag is found a temporary batch file will be created by the program. Then, instead of swapping and executing each single line, the temporary batch file is executed at once and deleted afterwards. This batch file will be placed in the subdirectory pointed to by the TMP or TEMP environment variable. The "dos [command]" line will be parsed for all built-in magic filenames the program supports (see page #23 for the complete list). Additional, there are four variables available as arguments for DOS commands: $day2, $day3, $week and $pday. $day2 returns a two character string containing the current day number; if the current day number is greater than 100, the first digit will not be included in the string returned by $day2. $day3 returns a three character string containing the current day number; leading zeroes will be added. $week is a two character string containing the number of the current week; here also leading zeroes will be added. $pday ("process day"): on Friday this variable returns the current day number; on each other day of the week it returns the day number of the most current Friday. This string is three characters long; leading zeroes will be included. With this additional variables programs which return the current day number ("DAYNBR") probably become obsolete. Example: the string "copy d:\inbound\nodelist.$day3 d:\misc" will be expanded to "copy d:\inbound\nodelist.033 d:\misc", assumed 33 is the current day number. See also the Sample.Cfg file included in the distribution archive for more examples on this feature. Ghostwriter [2.1] page 11 _________________________________________________ Server requests A very powerful feature is available through the built-in tag "server". Only a few statements are required to initialize execution of any batch file even from a remote location: Use "#define serveruser <firstname> [<lastname>]" in the define section of the configuration file. Then, use "#define serverpassword <password>" to indicate the keyword required to execute batch files from remote. Here's what happens if both keywords are set and the program is started with the one and only command line parameter "server": The netmail directory is searched for messages destined to <firstname> <lastname> as found on the "#define serveruser" line. If messages to this "user" are found a check for a match between the "Subject:" of the message and the <password> given on the "#define serverpassword" line is performed. If user name, password and destination system match the message is saved as batch file. A copy of the message will be forwarded as private netmail message to the sysop. Afterwards, this "message batch" is executed and deleted. If more than one message for "serveruser" was found first the messages are sorted by number. Then, each message is saved in ASCII format to a batch file and forwarded to the sysop. Finally, a master batch file is created. This master batch simply calls each single batch file and deletes it after execution. Finally, the master batch itself is deleted by the program. Of course, just like executing a "dos <command>" line, the program will be swapped nearly complete out of memory. The program always returns to the same drive and subdirectory where it resided before the "server" function was invoked. There is no restriction what can be done in this "message batches". Even all log files and the ghostwriter program itself may be deleted without "hanging" the system. The only system parameter not checked during server execution is the video mode currently used. Take care to always return to the same video mode used before invoking the server function. Ghostwriter [2.1] page 12 ________________________________________ How to use the "trigger" This function is similar to the "server" function. Instead of attempting to execute the message text as batch file DOS commands or predefined batch files will be executed if specific messages exist in the netmail subdirectory. "Triggers" are messages which must be addressed to your primary network address (additonal AKA addresses only will be checked in FrontDoor environments). First, these messages must not be received to be qualified for triggering any DOS command. Next, the "Subject" fields of this messages must match the "Subject" keyword in the Ghost.Cfg file (more on this a few lines later). If the "From" keyword of the defined trigger is not an empty line, the message's "From" field also must match. Those triggers are defined in the "#define" section of the configuration file. Here's the format for this section: #define trigger: This line is required to indicate the start of this section. If present it must not be preceded by any comment character. subject <message subject> (max. 72 characters): This is the message subject which will be compared with each single netmail message. A match is true if the shorter string is fully included in the longer string. from [firstname lastname] (max. 36 characters): Firstname Lastname are optional; the "from" line is *not* optional. If "from" is followed by a name "Subject" *and* "From" fields of a message must match; otherwise only the "Subject" fields must match to act as trigger. command <DOS command>: Any valid DOS command or batch file name. Use "first command;next command;next command;...;" to execute more than one DOS command or batch file. The last character of a multiple command line *must* be a semicolon. #end: This line is required to indicate the end of this section. It must not be preceded by any comment character. See the file Sample.Cfg included in the distribution package for more details on the "trigger" section. If the program is started with the parameter "trigger" all messages in the netmail directory will be searched for matching subjects (and matching "From" fields if the corresponding "From" field in Ghost.Cfg was not empty). If matching messages are found, the "Received" flag will be set by the program; next the DOS command associated to the "Subject" will be executed. As usual first an attempt to swap to EMS or harddisk will be done. That's it. Ghostwriter [2.1] page 13 ____________________________________________ Predefined variables There are 34 predefined variables you may use in the message text. Each one starts with the $ sign. The ghostwriter scans the text and substitutes the $variable with a value computed at run time. Here is a description of each variable. $anetlist This are the built-in "magic" filesnames $bbsnet the program supports. $egglist $fidonews The full filename of this nodelist and news- $netlist letter files are computed at execution time $nodediff and may be inserted into the message text. $nodelist $opcndiff The extension of these file names depends on $opcnlist your "#define packer" statement (see page 23) $pointnet $signodes $day number of the day in current month; digit without leading zeroes $dname name of the current day, possible values range from Sunday to Saturday $diskfree free space in kilobytes left on the currently logged drive $dosversion major and minor DOS version number $fromnet net number of the the message's origin system $fromnode node number of the message's origin system $frompoint point number of the point system currently using the program $fromzone the message origin zone as single number $memory free RAM space in kilobytes currently free. *Note*: this is not the same amount of memory available while shelling to DOS. $month current month number without leading zeroes $mname name of the current month; possible values range from January to December $name first name of the addressee of the message $origin name of the system currently using the program $tonet net number of the message's destination system Ghostwriter [2.1] page 14 $tonode node number of the message's destination system $topoint point number of the message's destination system $tozone the message destination zone as single number $time current time in the format hh:mm:ss $year current year in four digit format $bouncearea name of the not-received original message echomail area $bouncedate original message date $bouncelimit number of days in which the sysop missed to read (receive) the message The last three variables should only be used when the program performed the check for messages waiting for the sysop; see page 7 for more on this topic. Here are two special operators which add flexibility to the program: $include [full qualified drive-, path- and filename] If this operator is found in column #1 of the message text the ghostwriter attempts to read the file and include its contents into the message. No check is performed to verify that the file is a plain ASCII file. Unimaginable troubles may result if you use $include c:\dos\command.com in the Ghost.Cfg file. However: if your mailer/editor combination supports any information hidden behind ^a (01h) characters ("kludges") you may include those lines in any message line found in Ghost.Cfg or any file to $include in the message. Be sure to separate the $include directive and the filename with at least one space character. Always make sure that the resulting message created by one or more $include's does not exceed the maximal message size your message bundler is able to handle. The maximal message size ghostwriter can process is limited only by the amount of free memory at run time. The include file's text is not checked for any variable or special operator. If its text contains the strings $name or $diskfree they are imported as literals into the message text. In case the file specified for including in the message could not be found the line "[include file not found]" is inserted in the message. $dummy see page #19 for more on this keyword. ___________________________________________________ Message flags Ghostwriter [2.1] page 15 All messages created by ghostwriter will have the "local" bit set. File attaches generated by the ghostwriter additionally will have the "kill/sent" flag set; you don't need to specify "kill" in Ghost.Cfg. To individually set the message flags according to your or your message bundler's needs you may use any combination of the six flags the program supports: crash, hold, private, kill, request and update. One or more attribute flag keyword(s) on the "to [address]"-line, separated by at least one blank character from the zone:net/node.point field will set the message flags. Additional mailer specific flags also may be used; see page #18 for more details. ___________________________ Inter-zone messages: #define zonegate The statement "#define zonegate" will influence the contents of the message header when creating messages destined to other zones. If a "#define zonegate" line in the "#define" section of Ghost.Cfg was present messages to other zones will be re-routed to the gate for the destination zone. If this statement is missing the net and node number of the destination system will be written into the message header (this is the default). Find out the requirements for inter-zone messages or inter- zone file attaches of the software used on your system. No matter if "#define zonegate" is present or not: the ^aINTL kludge line will always be inserted to message headers for other zones. Ghostwriter [2.1] page 16 _________________________ National customization: #define country By default the program uses the English names to substitute any $dname or $mname found in Ghost.Cfg. If you like you may add a special section in the ghostwriters configuration file. Entitle this section with #define country in a line in Ghost.Cfg and add the seven names of the weekdays and the twelve monthnames, each one of them on a single line. Have a look at this section from the Ghost.Cfg I use on my system: ; --------------------------------------------------------------- #define country specific data for FRG, CH and A ; --------------------------------------------------------------- ; ; --------------------------------------------------------------- ; first the day names, start day is Sunday ; --------------------------------------------------------------- ; Sonntag Montag Dienstag Mittwoch Donnerstag Freitag Samstag ; ; --------------------------------------------------------------- ; now the monthnames in order 1..12 ; --------------------------------------------------------------- ; Januar Februar März April Mai Juni Juli August September Oktober November Dezember [Readers from other countries: please excuse the "funny cha- racters" shown in this example.] The program's strategy for this quite rudimentary "custom- ization" is to scan Ghost.Cfg for the "#define country" section. The next 19 non-comment lines are assumed to represent the names of the seven weekdays and the twelve monthnames used in your country. The first non-comment line encountered after #define Ghostwriter [2.1] page 17 country will be used for Sunday, line #7 of this section will represent Saturday, lines #8 to #19 will be used for the month numbers 1 to 12 if $mname is found anywhere in the message text. It's not necessary to include this section in Ghost.Cfg; the English names will be used if it is not found. But if you prefer to use this feature the #define country section must be located between the "from", "address", and "origin" section (if any) and the first "keyword", "dos", "to [name] [address] {flags}" and "path" section. __________________________________ Addressees list: #define group You may use the keyword #define group in any line of the programs configuration file to define groups of addressees. Take care: any "#define [parameter]" line must be located before the first "subject", "to" and "path" entry in the configuration file. The complete syntax for this entry line is as follows: #define group [groupname] {$file d:\dir\filename.ext} First comes the name of the group. This is exactly the same name you use later in the configuration file to refer to the group in the line containing the "to" statement. The maximum length of the group name is 40 characters; the only character which must not be used in ghe group name is the semicolon (;) as it is treated as "start of comment"-tag. The reference to the group is done by to group [groupname] <flags> <^amailer specific flags> following the keyword line and just before the "path" line in the Ghost.Cfg file. Next in the Ghost.Cfg file are lines containing the names, the network address of each group member and -- optionally -- the required message flags; each "record" on a single line. The first "; comment line" is interpreted as end of group-mark. The names of the group members may optionally be contained in an ASCII file which name is given by $file after the group's name. The format of this file is exactly the same as used in Ghost.Cfg following #define group or directly on each "to" line, i.e. [first name] [last name] [zone:net/node.point] {flags}. The programs also supports group members lists in the format generated for example by programs like Bob Hartman's "ParseLst": last name [comma] first name [blanks] [zone:] net/node. Since this file (Fidouser.Lst) contains no keywords for the message attribute flags ghostwriter sets the "private" flag (see also page #3). Ghostwriter [2.1] page 18 As with #define country each #define group section has to be located before any "keyword", "dos", "to" and "path" section in the configuration file. The number of #groups and the number of members of each group is limited only by the amount of free RAM while operating the program. Attention: *do not* use a group followed by one or more individual "to" lines. Messages only can be adressed by one or more "to" [firstname] [lastname] [address] {flags} line(s) or by one (and *only* one) "to #group [groupname]" line. Serious system crashes may occur if there's an attempt to mix both group and individual adressees references for one message. Optionally, mailer specific flags may be included after the group name. This is done by typing at least one blank character after the group name, a caret ("^", Alt-94), an "a" (Alt-97) character, immediately followed by any string required or supported by the mailer. This string will be converted to uppercase letters and included, hidden by a ^A (0x01 character) as very last kludge line right before the message text in a netmail message. Example: the statement "to group beta ^aflags dir" will teach the program is insert "0x01FLAGS DIR0x0D0x0A" as additional kludge line into each message to the beta group members. This ^a<mailer flag> string also can be used on each line, no matter if it's a group address line or a single "to" line. Here's the order those kludges will be inserted after the message header: INTL <destination> <origin> TOPT <point #> FMPT <point #> MAILER SPECIFIC STRING from "to group" line MAILER SPECIFIC STRING from single "to" line ____________________________ User-defined variable: the -d option The -d{variable} command line parameter only makes sense with a $dummy keyword on a line in the configuration file: if -dcon- tents_of_the_variable is present on the command line "contents of the variable" will be inserted for each $dummy found in the configuration file. This is not only true for the message text; also the process tag (the "Subject:" of a message, usually identical to the first command line parameter) or a network address may include one or more $dummy string. If you use $dummy as variable for a network address it's your responsibility to verify the proper format. Ghostwriter [2.1] page 19 Note the use of the underscore character: since DOS sepa- rates command line parameters by blanks it's necessary to substi- tute them by the _ character. If there are no underscores in the string following -d no substitution will take place. The same is true for the program's most important parameter: the keyword Ghost.Cfg will be scanned for. Note also that there is no blank between -d and the first character of the string you whish to use for each $dummy. If your message text contains a $dummy but no -dtext_for_dummy was found on the command line the ghostwriter will insert "-d parameter not found" into the message. The combination $include $dummy or the use in an address line "to New Sysop 1:170/$dummy" maybe is one of the most power- ful features of the program's part dealing with variables. _____________________ Alternate configuration file: the -f option By default the program searches for Ghost.Cfg in the same sub- directory where the Ghost.Exe file is located. If for any reason you whish to override this file you may include a full qualified filename on the command line immediately following the -f parameter (no blanks, please). This alternate configuration file must have the same struc- ture as Ghost.Cfg: optionally #define country, optionally #define group and "keyword", "dos", "to" and "path" sections. ____________________________ Generate kludge lines: the -k option Use -k anywhere on the command line to force insertion of kludge lines into the message text. As described on page #24 the ghost- writer optionally inserts up to two kludge lines into the message(s). If you experience any problems with your message bundler, especially when processing ghostwriter messages with file attaches, please do not use this option. Ghostwriter has been tested on systems operating with different software. No problems were encountered on nodes using Greg Dawson's Qmail 1.00a, Bob Hartman's ConfMail 3.31 and 4.0 combined with the Opus-rooted oMMM and FrontDoor working with TosScan. In none of these systems the kludge lines generated seemed to cause troubles. _____________________________ Use other sysop name: the -n option To use the program with a different sysop name as found in Binkley.Cfg, Config.Ra or Fd.Sys use the command line parameter "-n<new_name>" when invoking the program. Ghostwriter [2.1] page 20 As usual first and last name of <new_name> must be separated by an underscore character. <new_name> then replaces the sysop name in all program functions, including mail check. Of course the files Binkley.Cfg, Config.Ra and Fd.Sys never will be chan- ged; <new_name> just acts as temporary replacement. _____________________________________ No word wrap: the -s option By default each message line is terminated by a CR/LF sequence ("hard return"). To override this and leave line formatting up to the editor include the -s option somewhere on the command line. Anyway: lines ending with ":", ".", "!" and "?" will be treated as "hard returns". _____________________________________ No tear line: the -t option You may use the -t parameter to prevent creation of the tearline and the origin line if you don't like them or prefer to use those lines created by the echomail processor of your choice. _______________________________________ Tear line and origin line By default the programs appends an additional blank line and a tear line to the message. If the destination path of the message is an echo area (i.e. only a single message is generated) the program will append also an origin line. The contents of this origin line will be taken from an ASCII file named "Origin" in the message subdirectory. If this file doesn't exist the ghost- writer uses your system name as found in Binkley.Cfg, Fd.Sys or Config.Ra, followed by "(zone:net/node.point)". If neither Binkley.Cfg, Fd.Sys or Config.Ra could be located the words following "system" in Ghost.Cfg will be used. If there is no origin declared in Ghost.Cfg ghostwriter's last attempt before giving up and using "[The node without any origin] (zone:net/node.point)" will be to check the current directory for an existing Areas.Bbs or Origin file to extract the system's name from. If multiple messages are created ghostwriter assumes them to be privte messages for the matrix or the local area. No origin line will be appended to this messages. To prevent creation of the tear line use -t as command line parameter. The program never will append any tear and origin line to messages created in the netmail subdirectory. Ghostwriter [2.1] page 21 ___________________________________________________ File attaches To attach a file to a matrix message addressed to one person or a group of persons use the special command line parameter $file immediately followed by the full qualified name of the file you wish to attach. In Ghost.Cfg this entry is declared as keyword. Sample call: ghost $filed:\files\netstuff\nodediff.a12 Please note: there is no blank between $file and the name of file to attach. In the above example D:\Files\Netstuff\Nodediff.A12 becomes the "Subject:" of the message; the resulting messages will have the "file attach" and "kill/sent" flag set. When sending file attaches the programs also reports file- name, file size and date/time stamp of the file to send. This of course is only true if the file to be attached could be found in the moment the program is executing. Anyway: the program does not mind if the file to be attached not exists. Joker and wildcard characters may be used in the filename. The first matching file is attached to the message; if there are more matching files the program generates additional attach messages without message text for each matching filename found. If no single matching file was found the file attaches will not be built; don't include joker or wildcard characters in filenames to override this function and send a file though it is not yet existing in the subdirectory included in the filename. The attach filename may also be one of the "magic" filenames used on your system. First the program checks to see if the file to be attached exists. If this file could not be located and the "okfile" defined in Binkley.Cfg, Ghost.Cfg or Fd.Sys contains a description for this "magic", this description will be inserted as attach name. However: this is only true for the first matching "magic" filename. When sending multiple file attaches the program counts the number of files and the total file size in kilobytes and logs this to the screen. The filename may be followed by -d [nnn] on the same line in the Ghost.Cfg file. [nnn] must be a number between 1 and 65000; it allows you to build the attach message(s) only if the file is not older then [nnn] days. This flag may also be used if there are joker or wildcard characters in the filename. Ghostwriter [2.1] page 22 ___________________________________________________ File requests The "request" flag can be used to create file requests. The "Subject:" of the message will be the name of the file to be requested; the destination of the file request is taken from the "to name address { flags }" line of Ghost.Cfg. Any of the built- in "magic" filenames (see next section) the programs supports can be used as "keyword" command line parameter and as tag line in the program's configuration file. If one of this "magic" filenams is used it will be converted to the full filename as valid for the current system's date. An example: the call "ghost $fidonews" { more options } will scan Ghost.Cfg for the tag line "$fidonews". Since "$fidonews" is one of the "magic" filenames it is replaced by the currently valid full filename. This feature is very handy for requesting once a week the same Fido Newsletter or various Nodelist-/Nodediff-files. If instead of "request" the message flag "update" is used the program will generate a file update request. This means the destination system of the update request message will send the requested file only if the time and date stamp mark the file as newer than the one available on your system. _________________________________________________ Magic filenames These are the built-in magic filenames the program supports: $Anetlist, $BBSnet, $Egglist, $Fidonews, $Netlist, $Nodediff, $Nodelist, $Opcndiff, $Opcnlist, $Pointnet and $Signodes. If one of those names in encountered in the "$file..."-line the ghostwriter substitutes it by the actual filenames valid for the current date. For the date this documentation is written the following translation would take place: $fileD:\Out\$Nodelist --> $fileD:\Out\Nodelist.A82 $fileD:\Out\$Anetlist --> $fileD:\Out\Anetlist.A82 $fileD:\Out\$Fidonews --> $fileD:\Out\Fnews712.Arc See the file Sample.Cfg for more details and information regarding file attaches. _________________________________________ File compression method The keyword "#define packer [packer name]" in the #define section of the configuration file may be used to alter the filename extension the program uses to translate the built-in magic filenames. The default packing method currently used for the various nodelist and newsletter files is Arc; this is reflected by the letter "A" in the extension of any nodelist filename. Ghostwriter [2.1] page 23 #define packer may be followed by Lharc, Pak, Zip or Zoo. An example: if "#define packer Zip" is present, the magic filename $Fidonews for the current date would be computed to Fnews705.Zip; "#define packer Lharc" and $Nodediff would be converted to Nodediff.L33. ________________________________________ Override magic filenames The filename extensions for the various nodelist files are compu- ted by comparing the current date with the current day of the year. The most recent Friday is used to indicate for which day of the year the BBS listing is valid. If any new nodelist or nodediff file has to be attached on Thursday, the filename extension would be the Julian day number of the last Friday. The ghostwriter would be unable to automatically distribute the latest file. Use "#define magic- offset [n]" in the #define section of Ghost.Cfg to indicate which offset for the built-in magic filenames is valid on your system. [n] is assumed to be a single digit in the range of 1 to 4; any other value is ignored by the program. ___________________________________________ Optional kludge lines Ghostwriter optionally identifies its messages by inserting a kludge line as the very last line of the message. This kludge consists of a ^a (Ctrl-A, 0x01) character, immediately followed by the program's name, version number and an identification of the type of the node which is using the program. This either could be "[BinkleyTerm system]", "[FrontDoor system]" or "[RemoteAccess system]" depending on the type of the mailer or BBS configuration file the program found. If you use the program to generate file attaches a second klugde line will be inserted containing a 0x01 character and the word "attach", followed by the filename, the size in bytes and the date and time stamp of the file attached. This of course is true only if the attached file could be located on run time. See page #22 for more on file attaches and the paragraph on page #20 for the -k option. Ghostwriter [2.1] page 24 ____________________________________________ Errorlevels returned Errorlevel 0 indicates successful program termination, errorlevel 1 indicates matrix messages were created; errorlevel 2 indicates echomail messages were created. An errorlevel of 3 indicates that messages from or to the "purge" group were deleted during mailcheck. Errorlevel 4 reports troubles in creating the new messages (disk full, path or board number following "path" not existing, any other disk i/o error, important configuration files missing). Under no circumstances the program will stop with an annoy- ing "run time error xx at yyyy:zzzz. Hit any key to return to system". If possible, all open files will be closed by the program. Also, a full text error message will be written to the screen and the log file. There are three special errorlevels which only may occur in connection with the EMS/disk swapping before executing other DOS commands from within "Ghostwriter": 253: general EMS error 254: disk error 255: can't reallocate memory Errorlevel 255 only occurs if a resident program was started by a "dos [command]" line. This of course never should be done. Ghostwriter [2.1] page 25 ___________________________ Credits, new releases and "Thank you" Many thanks to Felix Kasza @ 2:310/11 for his support regarding the structure of Fd.Sys. Thanks also to Felix for proof reading the program's documentation, soothing my sometimes dubious use of the English language and the numberless late night phone calls he spent discussing new features, testing the program and writing bug reports. Thanks to John Alton @ 1:141/250 Wilton Woods Opus for sending me a lot of files describing troubles John encountered in creating file attaches with the ghostwriter and oMMM. Thank you, Sascha Vogt @ 2:310/7 for suggesting the "update" flag. Thank you, Luc Schoofs @ 2:295/26, for suggesting the "co- sysop" feature. Thanks to Jack Decker @ 1:154/8 for requesting the magic filenames "Opcndiff" and "Opcnlist". Special thanks to Bruce Bodger @ 1:170/400 for his suggestion of the "ondate" option, the bug reports and the EMS/disk swapping code Bruce sent me. Thank you, Borland International, for powerful tools like Turbo Pascal 5.5 and the Turbo Debugger; thank you, Kim Kokkonen and TurboPower Software for creating the marvellous "ExecSwap" unit; thank you, Big Blue, for your reliable computers (I still love my IBM XT 286). Finally: raise your hats to Tom Jennings for inventing Fido/Fidonet, the Binkley Trio and Joaquim Homrighausen for creating state of the art-mailers and to all other people in our community who keep the good work of programming and pumping megabytes of echomail round the world going on. The greatest "Thank you" again is addressed to Felix Kasza, 2:310/11, and Bruce Bodger, 1:170/400. Both are by far the very best beta testers I can imagine; besides this Felix is the only kind of "bossnode" suiting the needs of a former FidoNet region coordinator like me. Ghostwriter [2.1] page 26 The most recent version of my program is available from my bossnode, 2:310/11 Deep Node, HST-speed. I think Bruce Bodger's Truckstop BBS, 1:170/400, and John Alton's Wilton Woods Opus, 1:141/250, support the magic filenames GHOST or GHOSTWRITER. Also "Ghostwriter" should be available on any SDS node. You may re-pack the ghostwriter files using the compression utility of your choice, but take care to use "Ghost210" as file name and to include the file Sample.Cfg in the package you distribute. Feel free to mail any comments, suggestions or questions to Werner Berghofer, 2:310/11.100@Fidonet. Continue to enjoy sharing our common hobby and do your best to enthuse "new" people for the powerful medium electronic mail represents. Werner Berghofer, Vienna, April 15th, 1990. Ghostwriter [2.1] page 27 ___________________________________________________________ Index A define statuslog 5 Adam Hudson 2 define trigger 13 address 2, 3, 4 define zonegate 16 alternate configuration file disk swapping 25 20 DOS commands 10 Anetlist 23 DOS version 14 answer 8 Arc 23 E Areas.Bbs 5, 8, 21 Egglist 23 arguments for DOS commands 11 EMS 25 ASCII file 2, 4, 15, 18, 21 EMS memory 10 environment 2, 10 B errorlevel 11, 25 BBSnet 23 exit code 11 Binkley.Cfg 2, 21 Binkley Trio 26 F BinkleyTerm 2, 24 Fd.Sys 2, 6, 21, 26 Borland International 26 Felix Kasza 26 bouncelimit 7 Fidonet address format 4 Bruce Bodger 26 Fidonews 23 built-in magic filenames 23 Fidouser.Lst 3, 18 file attach 22 C file request 23 co-sysop 26 file size 22 comment character 4 file update request 23 comment line 4 first name 14 COMSPEC 10 FMPT 2, 4 Config.Ra 2, 21 Folder.Sys 6 configuration file 4, 17, 19, forward 8 25 four-dimensional 4 ConfMail 20 free RAM space 14 crash 16 free space 14 current time 15 FrontDoor 2, 24 D G date/time stamp 22 Ghost.Cfg 2, 4, 16, 17, 20 day 14 group 3, 9, 18 day2 11 day3 11 H day number 11 hard return 21 DAYNBR 11 hold 16 define cosysop 9 define country 17, 18 I define group 18 i/o error 25 define magicoffset 24 INTL 2 define messagebase 5 define packer 24 J define purge 9 Jack Decker 26 define QBBSpath 5 Joaquim Homrighausen 26 define serverpassword 12 John Alton 26 define serveruser 12 joker 22 Ghostwriter [2.1] page 28 K ParseLst 3, 18 keyword 4, 22 pday 11 kill 16 percent sign 4 Kim Kokkonen 26 point 2, 4, 21 kludge 24 point address format 4 kludge lines 20 point number 14 kludges 15 Pointnet 23 private 3, 16, 18 L process day 11 Lharc 24 purge 9 line formatting 21 local 16 Q log 5 Qmail 20 log format 5 QuickBBS message format 2 Luc Schoofs 26 R M re-direct 5 mailcheck 7 RemoteAccess 2, 24 mailer specific flags 19 report 8 matrix address 3 request 16, 23 maximal message size 15 resident program 25 memory map 10 run time error 25 message attribute flag 18 message bundler 15, 16, 20 S message flag 3, 16 Sascha Vogt 26 message format 2 SDS 27 month 14 semicolon 4 monthnames 17 server 12 MSGID 8 set BINKLEY 2 multiple file attaches 22 set FD 2 set RA 2 N Signodes 23 net number 14 special operator 15 Netlist 23 swap 10 netmail 2, 3, 4 swap file 10 network address 18 sysop 2, 3 node number 14 system 2, 3, 21 Nodediff 23 system crash 19 Nodelist 23 nodelist 2, 3 T nodelist compiler 3 TEMP 10 temporary batch file 11 O TMP 10 okfile 2, 3, 22 Tom Jennings 26 oMMM 20, 26 TOPT 2, 4 ondate 6 TosScan 20 onday 7 trailer lines 9 Opcndiff 23 trigger 13 Opcnlist 23 Turbo Debugger 26 Origin file 21 Turbo Pascal 5.5 26 TurboPower Software 26 P packer 23 U Pak 24 underscore 4, 20 Ghostwriter [2.1] page 29 update 16, 23 white space 4 wildcard 6, 22 V variable 14, 15 Z Zip 24 W zone 2, 4, 14, 21 week 11 Zoo 24 weekdays 17 Ghostwriter [2.1] page 30